MailMaster Plugin Definitions for MailMaster 1.1

Document last modified: 7/23/99

Table of Contents:

1. Introductions

2. Plugin Properties
  Required:
    kPluginType
    kVersion
    kMMPluginVersion
    
  Recommended:
    kMessageList
    
3. Mail App Plugins
  Required:
    MA_InitSession()
    MA_EndSession(yourInfo)
    MA_CheckMail()
    MA_CheckMailbox(itsMailbox)
    MA_GetMessage(msgRecord, messageRef)
    MA_DeleteMessage(messageRef)
    MA_QuitApps()
    
  Recommended:
    MA_MoveMessage(messageRef, newMailbox)

4. Database App Plugins
  Required:
    DB_AddMessage(dbInfo, msgRecord)
    DB_QuitApps()
    
5. Network Volume Plugins
  Required:
    NV_MountVolume(volEntry)
    NV_DismountVolume(volAlias)

6. Routines Provided
  LogInfo(logText)
  LogWarning(logText)
  LogError(logText)

7. License Issues



1. Introduction

The next version of the MailMaster application will use "load script"ed script
files to interface with EMail applications, Database applications, and Volume
Mounting methods instead of the current hard-coded definitions for Eudora 3,
FileMaker Pro, and various OSAXen.

To do so, external script files will need to have certain properties and
handlers so that the MailMaster can figure out what they are.

This is a work in progress document.  This version especially is just an
overview so you can see what I'm going to be looking for in a plugin, and
comments can be made to further adapt this for a wider set of programs.  As the
MM changes over and the plugins actually take form, this spec will solidify. -
Mike


2. Plugin Properties

All script plugins need to have these properties:

property kPluginType : "MA"
 kPluginType is a two letter code that identifies what kind of plugin this
script is.  There are three plugin types:
  "MA" : Mail
  "DB" : Database
  "NV" : Network Volume
 
property kVersion : {1,0,0}
  kVersion is a three number list in traditional Mac major, minor, more minor
format.  This is mostly for your own use.
 
property kMMPluginVersion : {1,1,0}
  kMMPluginVersion is the version of the MailMaster Plugin format for which this
plugin is written.  As the MailMaster evolves, your plugin may go out of date. 
With this, the MailMaster can filter out plugins that will not work with its
current version of plugins.
  kMMPluginVersions aren't necessarily equivalent between types.  (The mail
plugin version may be 1,1,0 while the database plugin version is 1,2,0 for
version 1.2 of MailMaster.)
 


You are not required to include this property, but it is recommended:

property kMessageList : {"An error occurred getting messages.", "An error
occurred opening the database."}
 -- If there is ever a localizable version of the MailMaster, there will
 -- also have to be localizable versions of the plugins.  If you move all
 -- the text strings you use to the front of the app, then a generic tool
 -- can be written to localize plugins, even if they're read only.
 

Notes for all plugins:

  You need to verify that your application exists and is running whenever you
talk to it.  Any applications you use are to be launched (not run or activated),
and you need to tell the MailMaster when you launched your app so it can close
it if necessary.  (Mechanism forthcoming.)



3. Mail App Plugins -- version 1.1.0

Mail App plugins provide these handlers:

MA_InitSession()
  MA_InitSession tells you to check your app to make sure it is running and
change any settings that need to be changed.  It can return a list of anything,
which will be saved and passed in to MA_EndSession.

  This is mostly used to disable settings that might otherwise interfere with
MailMaster operation, like periodic automatic mail downloading.


MA_EndSession(yourInfo)
  MA_EndSession is called when the MailMaster is about to go back to idle.  You
receive back the information returned from MA_InitSession, so you can return
settings to the way they were before MailMaster was triggered.


MA_CheckMail()
  MA_CheckMail makes sure the mail app is open (launching it if necessary) then
tells it to connect to the mail server and get mail.  It shouldn't return until
all the mail is downloaded, if at all possible.


MA_CheckMailbox(itsMailbox)
  MA_CheckMailbox takes the name of a mailbox and returns a list of messageRef. 
messageRef is currently a list of the mailbox name and the index into the
mailbox for Eudora, but this will (hopefully) change.  The best messageRef is
one that is not going to change if the messages are rearranged in their window
(indexes are bad).


MA_GetMessage(msgRecord, messageRef)
  MA_GetMessage takes a reference to a message and a Message Record, which is a
list of msgElementRecord.

msgElementRecord:  {msgHeader:"To", msgContents:"parody@pconline.com"}

  Currently the list of "headers" that the MailMaster handles is hard-coded in
MM:

msgHeader       msgContents
"To"            string
"From"          string
"Date"          string
"Time"          string
"Subject"       string
"Body"          string
"Attachments"   list of string paths

  Thus, your script will be taking a list of records and filling in the empty
contents side, then returning the record list.  In the future, the headers list
may be user-created, which may require a generic
message-with-full-headers-searching script. :(


MA_DeleteMessage(messageRef)
  MA_DeleteMessage takes a reference to a mesage and "deletes it".  In Eudora,
it goes into the trash folder.  (MM doesn't empty the trash.)


MA_QuitApps()
  MA_QuitApps should quit the mail app you use, and any extra things that are
running.  Make sure you verify first.
  

If possible, mail plugins should support these handlers:

MA_MoveMessage(messageRef, newMailbox)
  MA_MoveMessage (as implied) moves a message from one mailbox to another.  This
would get called instead of DeleteMessage, if the user doesn't want messages to
be deleted.
  
  

4. Database Plugins -- version 1.1.0

Database plugins currently only have to provide two handlers:

DB_AddMessage(dbInfo, msgRecord)
  DB_AddMessage adds a message to the database.  The msgRecord is the same thing
that was returned from MA_GetMessage.  The dbInfo is MailMaster's settings for
the Database, which you'll need to know how to open the database.

  In MM 1.0, dbInfo looks like:  

 dbinfo : {mlName:"MyName", dbName:"MyName ML Archive", mbName:"MyName",
openMethod:1, openInfo:"", newScript:"MakeNewRecord", beforeScript:"",
afterScript:"EndNewRecord", useBeforeScript:false, useAfterScript:true,
addSubject:true, addFrom:true, addTo:true, addBody:true, addDate:true,
addTime:true, addAttachments:true, attachmentsFolder:"My HD:Attachments"}

 openMethods:
  1=Direct (tell FMP to open dbName)
  2=Local File (tell FMP to open file openInfo)
  98=Run Script File (run script file openInfo)
  99=Run Script Line (run script openInfo) 

  MM 1.1 should add a "Network" type and a "Local File With Password" type, or
something similar (comments needed! :)

 Note that you'll need to open the database if necessary (and update MM that you
did so).  The Script options will be dealt with if/when someone writes this for
an app other than FileMaker Pro.

 DB_AddMessage returns the "index" of the message created.  Currently,
MailMaster assumes that the database used with it has a non-duplicatable serial
number field, and DB_AddMessage returns the new entry's value in that field. 
This is only required if you are going to save attachments (it needs some way to
link the attachments to the messages that spawned them).


DB_QuitApps()
  Like MA_QuitApps, DB_QuitApps quits any apps you might have used, if they're
running.



5. Network Volume Mounting Plugins -- version 1.1.0

You have to provide two handlers, and in most cases one will be written for you:

NV_MountVolume(volEntry)
  NV_MountVolume mounts the volume using the parameters passed in via volEntry. 
It should return an alias to the volume.

  volEntry looks like this:
{volName:"", volUser:"", volPassword:"", volServer:"", volZone:""}

  The settings are pretty obvious for mounting AppleTalk volumes.  For IP,
volServer will hold the server address, and volZone is ignored.


NV_DismountVolume(volAlias)
  NV_DismountVolume looks like this for most volumes:
  
  on NV_DismountVolume(volAlias)
    try
      tell application "Finder"
        put away {volAlias}
      end tell
    on error errTxt number errNum
      -- Insert LogError call here once LogError is written
    end try
  end NV_DismountVolume  

  ...but your network volume mounting method may require something different.
  
  

6. Routines provided by MailMaster and/or included in the plugin framework:

These routines are available for your plugins to call when doing their duty:

LogInfo(logText)
  LogInfo is called when you want to add something to the Log.  Generally, the
plugins won't need to call this (MM handles the informative entries in the log)
but it's there if you need it.


LogWarning(logText)
  LogWarning should be called when you encounter an error which doesn't
necessarily prevent MM from continuing but should be noted in the log.  A Mail
plugin might call LogWarning if a message specified a header that wasn't found
in the message, like "Reply-To".


LogError(logText)
  LogError is called when you encounter a serious error which stops operations
on either this message, this mailbox, or in general.  If the messageRef you are
passed doesn't exist, that's a job for LogError.

  Note that neither LogWarning or LogError actually abort your script.  You will
need to fire an error (and pass it on to MM) if you reach a point where your
routine can't continue.  This mechanism is still being worked out, but will
probably consist of three error codes you pass:

20001 "Cannot continue with this message/entry."
20002 "Cannot continue with this mailbox."
20003 "Cannot continue with this procedure."

  (Your try...on errors will need to look for these and pass them if found.)




7. License Issues

  I'm only going to keep the core MailMaster under license.  The initial plugins
will be free, editable scripts.  Any plugins you write you can license any way
you see fit, although I'm hoping you wouldn't go any farther than the postcard
that the MM asks for. :)


Mike Miller
ESG Labs
